/*
 * ----------------------------------------------------------------------------
 *  (C) Copyright European Telecommunications Standards Institute, 2001.
 *  All Rights Reserved.
 *
 *  All copies of this program, whether in whole or in part, and whether
 *  modified or not, must display this and all other embedded copyright
 *  and ownership notices in full.
 *
 * ----------------------------------------------------------------------------
 */
package org.etsi.ttcn.tri;

import java.io.Serializable;


/**
   <p>This interface consists of operations that are neccessary to
   implement the communication of the TTCN-3 ETS with the SUT. It
   includes operations to initialze the Test System Interface (TSI),
   establish connections to the SUT, and handle message and procedure
   based communication with the SUT. In addition, the triCommunication
   interface offers an operation to reset tje SUT Adapter (SA).

   <p>This part of the TriCommunication Interface handles the
   communication from the SA to the TE, i.e. the TE has to implement
   the operation defined here.
*/
public interface TriCommunicationTE extends Serializable {

    /**   
	  <p>This operation is called by the SA after it has received
	  a message from the SUT. It can only be used when tsiPortId
	  has been either previously mapped to a port of componentId
	  or has been referenced in the previous triExecuteTestCase
	  statement. In the invocation of a triEnqueueMessage
	  operation receivedMessage shall contain an encoded value.

	  <p>This operation shall pass the message to the TE
	  indicating the port of the component componentId to which
	  the TSI port tsiPortId is mapped.  The decoding of
	  receivedMessage has to be done in the TE.

	  @param tsiPortId identifier of the test system interface port
	  via which the message is enqueued by the SUT Adapter
	
	  @param sutAddress (optional) source address within the SUT
	
	  @param componentId identifier of the receiving test component

	  @param receivedMessage the encoded received message

	  @see "TRI-Definition 7.5.6"
    */
    public void triEnqueueMsg(TriPortId tsiPortId, 
	TriAddress sutAddress, TriComponentId componentId,
	TriMessage receivedMessage);

    /** 
	<p>This operation can be called by the SA after it has
	received a procedure call from the SUT. It can only be used
	when tsiPortId has been either previously mapped to a port of
	componentId or referenced in the previous triExecute
	statement.  In the invocation of a triEnqueueCall operation
	all in and inout procedure parameters contain encoded
	values. All out procedure parameters shall contain the
	distinct value of null since they are only relevant in the
	reply on the procedure call but not in the procedure call
	itself.

	<p>The TE can enqueue this procedure call with the signature
	identifier signatureId at the port of the component
	componentId to which the TSI port tsiPortId is mapped. The
	decoding of procedure parameters has to be done in the TE.  No
	error shall be indicated by the TE in case the value of any
	out parameter is non-null.

	@param tsiPortId identifier of the test system interface port via
	which the procedure call is enqueued by the SUT Adapter

	@param SUTaddress (optional) source address within the SUT

	@param componentId identifier of the receiving test component

	@param signatureId identifier of the signature of the procedure
	call

	@param parameterList a list of encoded parameters which are part
	of the indicated signature. The parameters in parameterList are
	ordered as they appear in the TTCN-3 signature declaration.

	@see "TRI-Definition 7.5.10"
    */
    public void triEnqueueCall(TriPortId tsiPortId, 
	TriAddress SUTaddress, TriComponentId componentId, 
	TriSignatureId signatureId, TriParameterList parameterList );

    /**  
	 <p>This operation can be called by the SA after it has
	 received a reply from the SUT. It can only be used when
	 tsiPortId has been either previously mapped to a port of
	 componentId or referenced in the previous triExecute
	 statement.  In the invocation of a triEnqueueReply operation
	 all out and inout procedure parameters and the return value
	 contain encoded values. All in procedure parameters shall
	 contain the distinct value of null since they are only of
	 relevance to the procedure call but not in the reply to the
	 call.  If no return type has been defined for the procedure
	 signature in the TTCN-3 ATS, the distinct value null shall be
	 used for the return value.
	
	 <p>The TE can enqueue this reply to the procedure call with
	 the signature identifier signatureId at the port of the
	 component componentId to which the TSI port tsiPortId is
	 mapped.  The decoding of the procedure parameters has to be
	 done within the TE.  No error shall be indicated by the TE in
	 case the value of any in parameter or a non-defined return
	 value is non-null.
    
	 @param tsiPortId identifier of the test system interface port via
	 which the reply is enqueued by the SUT Adapter

	 @param address (optional) source address within the SUT

	 @param componentId identifier of the receiving test component

	 @param signatureId identifier of the signature of the procedure
	 call

	 @param parameterList a list of encoded parameters which are part
	 of the indicated signature. The parameters in parameterList are
	 ordered as they appear in the TTCN-3 signature declaration.

	 @param returnValue (optional) encoded return value of the
	 procedure call

	 @see "TRI-Definition 7.5.11"
    */
    public void triEnqueueReply(TriPortId tsiPortId, TriAddress address, 
	TriComponentId componentId, TriSignatureId signatureId, 
	TriParameterList parameterList, TriParameter returnValue);

    /** 
	<p>This operation can be called by the SA after it has
	received a reply from the SUT. It can only be used when
	tsiPortId has been either previously mapped to a port of
	componentId or referenced in the previous triExecuteTestCase
	statement.  In the invocation of a triEnqueueException
	operation exception shall contain an encoded value.

	<p>The TE can enqueue this exception for the procedure call
	with the signature identifier signatureId at the port of the
	component componentId to which the TSI port tsiPortId is
	mapped.  The decoding of the exception has to be done within
	the TE.

	@param tsiPortId identifier for the test system interface port via
	which the exception is enqueued by the SUT Adapter

	@param sutAddress (optional) source address within the SUT

	@param signatureId identifier of the signature of the procedure
	call which the exception is associated with

	@param exception the encoded exception

	@see "TRI-Definition 7.5.12"
    */
    public void triEnqueueException(TriPortId tsiPortId, 
	TriAddress sutAddress, TriComponentId componentId, 
	TriSignatureId signatureId, TriException exception);
}
